.TH std::advance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::advance \- std::advance

.SH Synopsis
   Defined in header <iterator>
   template< class InputIt, class Distance >           \fI(until C++17)\fP
   void advance( InputIt& it, Distance n );
   template< class InputIt, class Distance >           \fI(since C++17)\fP
   constexpr void advance( InputIt& it, Distance n );

   Increments given iterator it by n elements.

   If n is negative, the iterator is decremented. In this case, InputIt must meet the
   requirements of LegacyBidirectionalIterator, otherwise the behavior is undefined.

.SH Parameters

   it      -     iterator to be advanced
   n       -     number of elements it should be advanced
.SH Type requirements
   -
   InputIt must meet the requirements of LegacyInputIterator.

.SH Return value

   \fI(none)\fP

.SH Complexity

   Linear.

   However, if InputIt additionally meets the requirements of
   LegacyRandomAccessIterator, complexity is constant.

.SH Notes

   The behavior is undefined if the specified sequence of increments or decrements
   would require that a non-incrementable iterator (such as the past-the-end iterator)
   is incremented, or that a non-decrementable iterator (such as the front iterator or
   the singular iterator) is decremented.

.SH Possible implementation

   See also the implementations in libstdc++ and libc++.

                                  Non-constexpr version
   namespace detail
   {
       template<class It>
       void do_advance(It& it, typename std::iterator_traits<It>::difference_type n,
                       std::input_iterator_tag)
       {
           while (n > 0)
           {
               --n;
               ++it;
           }
       }

       template<class It>
       void do_advance(It& it, typename std::iterator_traits<It>::difference_type n,
                       std::bidirectional_iterator_tag)
       {
           while (n > 0)
           {
               --n;
               ++it;
           }
           while (n < 0)
           {
               ++n;
               --it;
           }
       }

       template<class It>
       void do_advance(It& it, typename std::iterator_traits<It>::difference_type n,
                       std::random_access_iterator_tag)
       {
           it += n;
       }
   } // namespace detail

   template<class It, class Distance>
   void advance(It& it, Distance n)
   {
       detail::do_advance(it, typename std::iterator_traits<It>::difference_type(n),
                          typename std::iterator_traits<It>::iterator_category());
   }
                                    constexpr version
   template<class It, class Distance>
   constexpr void advance(It& it, Distance n)
   {
       using category = typename std::iterator_traits<It>::iterator_category;
       static_assert(std::is_base_of_v<std::input_iterator_tag, category>);

       auto dist = typename std::iterator_traits<It>::difference_type(n);
       if constexpr (std::is_base_of_v<std::random_access_iterator_tag, category>)
           it += dist;
       else
       {
           while (dist > 0)
           {
               --dist;
               ++it;
           }
           if constexpr (std::is_base_of_v<std::bidirectional_iterator_tag, category>)
               while (dist < 0)
               {
                   ++dist;
                   --it;
               }
       }
   }

.SH Example


// Run this code

 #include <iostream>
 #include <iterator>
 #include <vector>

 int main()
 {
     std::vector<int> v{3, 1, 4};

     auto vi = v.begin();
     std::advance(vi, 2);
     std::cout << *vi << ' ';

     vi = v.end();
     std::advance(vi, -2);
     std::cout << *vi << '\\n';
 }

.SH Output:

 4 1

.SH See also

   next            increment an iterator
   \fI(C++11)\fP         \fI(function template)\fP
   prev            decrement an iterator
   \fI(C++11)\fP         \fI(function template)\fP
   distance        returns the distance between two iterators
                   \fI(function template)\fP
   ranges::advance advances an iterator by given distance or to a given bound
   (C++20)         (niebloid)
